@aws-cdk/aws-events

What is @aws-cdk/aws-events?

@aws-cdk/aws-events is an AWS Cloud Development Kit (CDK) library that allows you to define and manage Amazon EventBridge resources using code. EventBridge is a serverless event bus that makes it easier to build event-driven applications by connecting application data from your own applications, integrated Software-as-a-Service (SaaS) applications, and AWS services.

What are @aws-cdk/aws-events's main functionalities?

Creating an Event Bus

This code sample demonstrates how to create a new EventBridge event bus using the AWS CDK. The event bus can be used to receive and route events.

const events = require('@aws-cdk/aws-events');
const cdk = require('@aws-cdk/core');

const app = new cdk.App();
const stack = new cdk.Stack(app, 'EventBusStack');

const eventBus = new events.EventBus(stack, 'MyEventBus', {
  eventBusName: 'my-event-bus'
});

app.synth();

Creating a Rule

This code sample demonstrates how to create an EventBridge rule that triggers when an EC2 instance changes state to 'running'. The rule targets a Lambda function.

const events = require('@aws-cdk/aws-events');
const targets = require('@aws-cdk/aws-events-targets');
const cdk = require('@aws-cdk/core');

const app = new cdk.App();
const stack = new cdk.Stack(app, 'EventRuleStack');

const rule = new events.Rule(stack, 'MyRule', {
  eventPattern: {
    source: ['aws.ec2'],
    detailType: ['EC2 Instance State-change Notification'],
    detail: {
      state: ['running']
    }
  }
});

rule.addTarget(new targets.LambdaFunction(myLambdaFunction));

app.synth();

Scheduling Events

This code sample demonstrates how to create a scheduled EventBridge rule that triggers every 5 minutes. The rule targets a Lambda function.

const events = require('@aws-cdk/aws-events');
const targets = require('@aws-cdk/aws-events-targets');
const cdk = require('@aws-cdk/core');

const app = new cdk.App();
const stack = new cdk.Stack(app, 'ScheduledEventStack');

const rule = new events.Rule(stack, 'MyScheduledRule', {
  schedule: events.Schedule.rate(cdk.Duration.minutes(5))
});

rule.addTarget(new targets.LambdaFunction(myLambdaFunction));

app.synth();

Other packages similar to @aws-cdk/aws-events

aws-sdk

The aws-sdk package is the official AWS SDK for JavaScript, which provides a comprehensive set of tools for interacting with AWS services, including EventBridge. Unlike @aws-cdk/aws-events, which is used for defining infrastructure as code, aws-sdk is used for making API calls to AWS services.

serverless

The serverless framework is a popular open-source framework for building and deploying serverless applications. It supports AWS Lambda and EventBridge, among other services. While @aws-cdk/aws-events focuses on infrastructure as code, serverless provides a higher-level abstraction for deploying serverless applications.

pulumi

Pulumi is an infrastructure as code tool that supports multiple cloud providers, including AWS. It allows you to define and manage cloud resources using familiar programming languages. Pulumi can be used to manage EventBridge resources similarly to @aws-cdk/aws-events, but it offers a different approach and supports multiple clouds.

README

AWS CloudWatch Events Construct Library

Amazon CloudWatch Events delivers a near real-time stream of system events that describe changes in AWS resources. For example, an AWS CodePipeline emits the State Change event when the pipeline changes it's state.

• Events: An event indicates a change in your AWS environment. AWS resources can generate events when their state changes. For example, Amazon EC2 generates an event when the state of an EC2 instance changes from pending to running, and Amazon EC2 Auto Scaling generates events when it launches or terminates instances. AWS CloudTrail publishes events when you make API calls. You can generate custom application-level events and publish them to CloudWatch Events. You can also set up scheduled events that are generated on a periodic basis. For a list of services that generate events, and sample events from each service, see CloudWatch Events Event Examples From Each Supported Service.
• Targets: A target processes events. Targets can include Amazon EC2 instances, AWS Lambda functions, Kinesis streams, Amazon ECS tasks, Step Functions state machines, Amazon SNS topics, Amazon SQS queues, and built-in targets. A target receives events in JSON format.
• Rules: A rule matches incoming events and routes them to targets for processing. A single rule can route to multiple targets, all of which are processed in parallel. Rules are not processed in a particular order. This enables different parts of an organization to look for and process the events that are of interest to them. A rule can customize the JSON sent to the target, by passing only certain parts or by overwriting it with a constant.

The EventRule construct defines a CloudWatch events rule which monitors an event based on an event pattern and invoke event targets when the pattern is matched against a triggered event. Event targets are objects that implement the IEventTarget interface.

Normally, you will use one of the source.onXxx(name[, target[, options]]) -> EventRule methods on the event source to define an event rule associated with the specific activity. You can targets either via props, or add targets using rule.addTarget.

For example, to define an rule that triggers a CodeBuild project build when a commit is pushed to the "master" branch of a CodeCommit repository:

const onCommitRule = repo.onCommit('OnCommitToMaster', project, 'master');

You can add additional targets, with optional input transformer using eventRule.addTarget(target[, input]). For example, we can add a SNS topic target which formats a human-readable message for the commit.

For example, this adds an SNS topic as a target:

onCommitRule.addTarget(topic, {
    template: 'A commit was pushed to the repository <repo> on branch <branch>',
    pathsMap: {
        branch: '$.detail.referenceName',
        repo: '$.detail.repositoryName'
    }
});

Changelog

0.19.0 (2018-12-04)

Bug Fixes

• aws-cdk: add '-h' flag to bring up help (#1274) (47dafb0), closes #1259
• aws-cloudfront: Allow to disable IPv6 on cloudfront distribution (#1244) (10b7092), closes #1243
• aws-cloudtrail: correct S3 bucket policy and dependency chain (#1268) (0de2da8), closes #1172
• aws-ec2: fix code generation of IcmpPing (#1235) (6a13a18), closes #1231
• cdk: don't use instanceof in App (#1249) (a45c3bd), closes #1245
• cdk init: rename 'dotnet' to 'csharp' (#1210) (da6a799), closes #1123
• cdk init: update 'app' init template (#1209) (0287109), closes #1124 #1128 #1214

Features

• aws-codebuild: allow using docker image assets as build images (#1233) (72413c1), closes #1232 #1219
• aws-codebuild: rename the Project methods for adding Actions to CodePipeline. (#1254) (825e448), closes #1211
• aws-ecr: add an ECR Repository source CodePipeline Action. (#1255) (01cc8a2)
• app-delivery: IAM policy for deploy stack (#1165) (edc9a21), closes #1165 #1151
• Update to CloudFormation spec v2.16.0 (#1280) (9df5c54)

BREAKING CHANGES TO EXPERIMENTAL FEATURES

• aws-codebuild: ecr.RepositoryRef has been replaced by ecr.IRepository, which means that RepositoryRef.import is now Repository.import. Futhermore, the CDK Toolkit must also be upgraded since the docker asset protocol was modified. IRepository.grantUseImage was renamed to IRepository.grantPull.
• aws-codebuild: addBuildToPipeline was renamed to addToPipeline and addTestToPipeline was renamed to addPipelineToTest in order to align with naming conventions.
• CloudFormationCapabilities.IAM renamed to CloudFormation.AnonymousIAM and PipelineCloudFormationDeployActionProps.capabilities?: CloudFormationCapabilities[] has been changed to PipelineCloudFormationDeployActionProps.capabilities?: CloudFormationCapabilities no longer an array. PipelineCloudFormationDeployActionProps.fullPermissions?: has been renamed to PipelineCloudFormationDeployActionProps.adminPermissions: and is required instead of optional.

<a name="0.18.1"></a>